<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
          "http://www.w3.org/TR/html4/loose.dtd">

<html lang="en">

<head>
  <meta http-equiv="Content-Type"
        content="text/html; charset=utf-8">
  <meta http-equiv="Content-Style-Type"
        content="text/css">
  <meta http-equiv="Content-Script-Type"
        content="text/javascript">
  <meta name="description"
        content="FreeType Documentation - Design - Module Classes">
  <meta name="Author"
        content="David Turner">

  <link rel="icon"
        href="../image/favicon_-90.ico">
  <link rel="shortcut icon"
        href="../image/favicon_-90.ico">
  <link rel="stylesheet"
        type="text/css"
        href="../css/freetype2_-90.css">

  <script type="text/javascript"
          src="../../../js/freetype2.js">
  </script>

  <title>FreeType Design | Module Classes</title>
</head>


<body>

<div id="top"
     class="bar">
  <h1><a href="http://freetype.org/index.html">FreeType</a>
    Design&nbsp;/&nbsp;IV</h1>
</div>


<div id="wrapper">

<div class="colmask leftmenu">
  <div class="colright">
    <div class="col1wrap">
      <div class="col1">


        <!-- ************************************************** -->

        <div id="module-classes">
          <h2>IV. Module Classes</h2>

          <p>We will now try to explain more precisely
            the <em>types</em> of modules that FreeType&nbsp;2 is
            capable of managing.</p>

          <ul>
            <li>
              <p><em>Renderer</em> modules manage scalable glyph
                images.  This means <em>transforming</em> them,
                computing their <em>bounding box</em>,
                and <em>converting</em> them to
                either <em>monochrome</em> or <em>anti-aliased</em>
                bitmaps.</p>

              <p>Note that FreeType&nbsp;2 is capable of dealing
                with <em>any</em> kind of glyph images, as long as a
                renderer module is provided for it.  The library comes
                by default with four renderers.</p>

              <table>
                <tr valign=top>
                  <td>
                    <p><tt>raster</tt></p>
                  </td>
                  <td>
                    <p>Convert vectorial outlines
                    to <em>monochrome</em> bitmaps.</p>
                  </td>
                </tr>

                <tr valign=top>
                  <td>
                    <p><tt>smooth</tt></p>
                  </td>
                  <td>
                    <p>Convert vectorial outlines to
                    <em>anti-aliased</em> pixmaps (using 256 levels of
                    gray).  Note that this renderer also supports
                    direct span generation, that is, it provides a
                    hook into the engine so that the application can
                    manipulate the rendering results itself, instead
                    of letting the rasterizer fill a pixmap.
                    See <a href="../tutorial/example4.cpp">this
                    tutorial demo file</a> for an example.</p>
                  </td>
                </tr>

                <tr valign=top>
                  <td>
                    <p><tt>sdf</tt></p>
                  </td>
                  <td>
                    <p>Convert vectorial outlines to
                    8-bit <em>Signed Distance Field</em> (SDF)
                    bitmaps.</p>
                  </td>
                </tr>

                <tr valign=top>
                  <td>
                    <p><tt>bsdf</tt></p>
                  </td>
                  <td>
                    <p>Convert bitmap glyphs to 8-bit <em>Signed
                    Distance Field</em> (SDF) bitmaps.</p>
                  </td>
                </tr>
              </table>

              <p>The <a href="https://gitlab.freedesktop.org/freetype/freetype-demos/-/blob/master/src/ftsdf.c"><code>ftsdf</code></a>
                FreeType demo program supports both
                the <code>sdf</code> and <code>bsdf</code> renderers;
                all other (graphical) demo
                programs <code>raster</code>
                and <code>smooth</code>.</p>

            </li>

            <li>
              <p><em>Font driver</em> modules support one or more
                specific font formats.  Here is a list with the most
                important ones.</p>

              <table>
                <tr valign=top>
                  <td>
                    <p><tt>truetype</tt></p>
                  </td>
                  <td>
                    <p>TrueType fonts.</p>
                  </td>
                </tr>
                <tr valign=top>
                  <td>
                    <p><tt>type1</tt></p>
                  </td>
                  <td>
                    <p>Postscript Type&nbsp;1 fonts, both in binary
                      (<tt>.pfb</tt>) or ASCII (<tt>.pfa</tt>)
                      formats, including Multiple Master fonts.</p>
                  </td>
                </tr>
                <tr valign=top>
                  <td>
                    <p><tt>cid</tt></p>
                  </td>
                  <td>
                    <p>Postscript CID-keyed fonts.</p>
                  </td>
                </tr>
                <tr valign=top>
                  <td>
                    <p><tt>cff</tt></p>
                  </td>
                  <td>
                    <p>OpenType CFF and CFF2, bare CFF, and CEF fonts
                      (CEF is a derivative of CFF used by Adobe in its
                      SVG viewer).</p>
                  </td>
                </tr>
                <tr valign=top>
                  <td>
                    <p><tt>winfonts</tt></p>
                  </td>
                  <td>
                    <p>Windows bitmap fonts (i.e., <tt>.fon</tt> and
                      <tt>.fnt</tt>).</p>
                  </td>
                </tr>
              </table>

              <p>Note that font drivers can support bitmapped or
                scalable glyph images.  A given font driver that
                supports B&eacute;zier outlines
                through <tt>FT_Outline</tt> can also provide its own
                hinter, or rely on FreeType's <tt>autofit</tt>
                module for auto-hinting.</p>

              <p>Note further that font drivers need some
                <em>services</em> to be present: a typical example is
                <code>FONT_FORMAT</code> to return the name of a font
                format.  This is discussed in
                the <a href="design-6.html">next section</a>.
            </li>

            <li>
              <p><em>Helper</em> modules are used to hold shared code
                that is often used by several font drivers, or even
                other modules.  The most important are as follows.</p>

              <table>
                <tr valign=top>
                  <td>
                    <p><tt>sfnt</tt></p>
                  </td>
                  <td>
                    <p>Support for font formats based on
                      the <tt>SFNT</tt> storage scheme: TrueType,
                      OpenType, as well as other variants (like
                      TrueType fonts that only contain embedded
                      bitmaps).</p>
                  </td>
                </tr>
                <tr valign=top>
                  <td>
                    <p><tt>psnames</tt></p>
                  </td>
                  <td>
                    <p>Various useful functions related to glyph name
                      ordering and Postscript encodings and charsets.
                      For example, this module is capable of
                      automatically synthetizing a Unicode charmap
                      from a Type&nbsp;1 glyph name dictionary.</p>
                  </td>
                </tr>
                <tr valign=top>
                  <td>
                    <p><tt>psaux</tt></p>
                  </td>
                  <td>
                    <p>Auxiliary functions related to Postscript
                      charstring decoding, as needed by
                      the <tt>type1</tt>, <tt>cid</tt>,
                      and <tt>cff</tt> drivers.</p>
                  </td>
                </tr>
              </table>
            </li>
            <li>
              <p>Finally, the <em>auto-hinter</em> module
                (<tt>autofit</tt>) has a specific role in
                FreeType&nbsp;2, as it can be used automatically
                during glyph loading to process individual glyph
                outlines when a font driver doesn't provide its own
                hinting engine.</p>

              <p>A paper published in the EuroTeX 2003 proceedings,
                titled <a href="http://www.tug.org/TUGboat/tb24-3/lemberg.pdf"><em>Real-Time
                Grid Fitting of Typographic Outlines</em></a>, gives
                further insight into the auto-hinting system's inner
                workings.</p>
            </li>
          </ul>

          <p>We will now study how modules are described, then managed
            by the library.</p>


          <h3 id="section-1">1. The <tt>FT_Module_Class</tt>
            Structure</h3>

          <p>Here is the definition of <tt>FT_Module_Class</tt>, with
            some explanations.  The following code is taken from
            <tt>ftmodapi.h</tt>.</p>

          <pre>
typedef struct  FT_Module_Class_
{
  FT_ULong               module_flags;
  FT_Int                 module_size;
  const FT_String*       module_name;
  FT_Fixed               module_version;
  FT_Fixed               module_requires;

  const void*            module_interface;

  FT_Module_Constructor  module_init;
  FT_Module_Destructor   module_done;
  FT_Module_Requester    get_interface;

} FT_Module_Class;</pre>

          <p>A description of its fields.</p>

          <table>
            <tr valign=top>
              <td>
                <p><tt>module_flags</tt></p>
              </td>
              <td>
                <p>A set of bit flags to describe the module's
                  category.  Valid values are listed below.</p>

                <ul>
                  <li>
                    <tt>FT_MODULE_FONT_DRIVER</tt> if the module is a
                    font driver
                  </li>
                  <li>
                    <tt>FT_MODULE_RENDERER</tt> if the module is a
                    renderer
                  </li>
                  <li>
                    <tt>FT_MODULE_HINTER</tt> if the module is an
                    auto-hinter
                  </li>
                  <li>
                    <tt>FT_MODULE_DRIVER_SCALABLE</tt> if the module
                    is a font driver supporting scalable glyph formats
                  </li>
                  <li>
                    <tt>FT_MODULE_DRIVER_NO_OUTLINES</tt> if the
                    module is a font driver supporting scalable glyph
                    formats that <em>cannot</em> be described by
                    an <tt>FT_Outline</tt> object
                  </li>
                  <li>
                    <tt>FT_MODULE_DRIVER_HAS_HINTER</tt> if the module
                    is a font driver that provides its own hinting
                    scheme/algorithm
                  </li>
                  <li>
                    <tt>FT_MODULE_DRIVER_HINTS_LIGHTLY</tt> if the
                    module is a font driver that generates
                    &lsquo;light&rsquo; hints (this is, only along the
                    vertical axis).
                  </li>
                </ul>
              </td>
            </tr>
            <tr valign=top>
              <td>
                <p><tt>module_size</tt></p>
              </td>
              <td>
                <p>An integer that gives the size in <em>bytes</em> of
                  a given module object.  This should <em>never</em>
                  be less than <tt>sizeof(FT_ModuleRec)</tt>, but can
                  be more if the module needs to sub-class the
                  base <tt>FT_ModuleRec</tt> class.</p>
              </td>
            </tr>
            <tr valign=top>
              <td>
                <p><tt>module_name</tt></p>
              </td>
              <td>
                <p>The module's internal name, coded as a simple ASCII
                  C&nbsp;string.  There can't be two modules with the
                  same name registered in a given <tt>FT_Library</tt>
                  object.  However, <tt>FT_Add_Module</tt> uses
                  the <tt>module_version</tt> field to detect module
                  upgrades and perform them cleanly, even at
                  run-time.</p>
              </td>
            </tr>
            <tr valign=top>
              <td>
                <p><tt>module_version</tt></p>
              </td>
              <td>
                <p>A 16.16 fixed-point number giving the module's
                  major and minor version numbers.  It is used to
                  determine whether a module needs to be upgraded when
                  calling <tt>FT_Add_Module</tt>.</p>
              </td>
            </tr>
            <tr valign=top>
              <td>
                <p><tt>module_requires</tt></p>
              </td>
              <td>
                <p>A 16.16 fixed-point number giving the version of
                  FreeType&nbsp;2 that is required to install this
                  module.  The default value is 0x20000 for FreeType
                  version&nbsp;2.x</p>
              </td>
            </tr>
            <tr valign=top>
              <td>
                <p><tt>module_interface</tt></p>
              </td>
              <td>
                <p>Most modules support one or more
                  &lsquo;interfaces&rsquo;, i.e., tables of function
                  pointers.  This field points to the module's main
                  interface, if there is one.  It is a short-cut that
                  prevents users of the module to
                  call <tt>get_interface</tt> each time they need to
                  access one of the object's common entry points.</p>

                <p>Note that it is optional, and can be set to NULL.
                  Other interfaces can also be accessed through
                  the <tt>get_interface</tt> field.</p>
              </td>
            </tr>
            <tr valign=top>
              <td>
                <p><tt>module_init</tt></p>
              </td>
              <td>
                <p>A pointer to a function to initialize the fields of
                  a fresh new <tt>FT_Module</tt> object.  It is
                  called <em>after</em> the module's base fields have
                  been set by the library, and is generally used to
                  initialize the fields of <tt>FT_ModuleRec</tt>
                  subclasses.</p>

                <p>Most module classes set it to NULL to indicate that
                  no extra initialization is necessary.</p>
              </td>
            </tr>
            <tr valign=top>
              <td>
                <p><tt>module_done</tt></p>
              </td>
              <td>
                <p>A pointer to a function to finalize the fields of a
                  given <tt>FT_Module</tt> object.  Note that it is
                  called <em>before</em> the library unsets the
                  module's base fields, and is generally used to
                  finalize the fields of <tt>FT_ModuleRec</tt>
                  subclasses.</p>

                <p>Most module classes set it to NULL to indicate that
                  no extra finalization is necessary</p>
              </td>
            </tr>
            <tr valign=top>
              <td>
                <p><tt>get_interface</tt></p>
              </td>
              <td>
                <p>A pointer to a function to request the address of a
                  given module interface.  Set it to NULL if you don't
                  need to support additional interfaces but the main
                  one.</p>
              </td>
            </tr>
          </table>


          <h3 id="section-2">2. The <tt>FT_Module</tt> Type</h3>

          <p>The <tt>FT_Module</tt> type is a handle (i.e., a pointer)
            to a given module object or instance, whose base structure
            is given by the internal <tt>FT_ModuleRec</tt> type.  We
            will intentionally <em>not</em> describe this structure
            here, as there is no point to look so far into the
            library's design.</p>

          <p>When <tt>FT_Add_Module</tt> is called, it first allocates
            a new module instance, using the <tt>module_size</tt>
            class field to determine its byte size.  The function
            initializes the root <tt>FT_ModuleRec</tt> field, then
            calls the class-specific initializer <tt>module_init</tt>
            when this field is not set to NULL.</p>

          <p>Note that the library defines several sub-classes of
            <tt>FT_ModuleRec</tt>.</p>

          <ul>
            <li>
              <p><tt>FT_Renderer</tt> for renderer modules</p>
            </li>
            <li>
              <p><tt>FT_Driver</tt> for font driver modules</p>
            </li>
            <li>
              <p><tt>FT_AutoHinter</tt> for the auto-hinter</p>
            </li>
          </ul>

          <p>Helper modules use the base <tt>FT_ModuleRec</tt>
            type.</p>
        </div>

         <!-- ************************************************** -->

        <div class="updated">
          <p>Last update: 27-Jan-2022</p>
        </div>
      </div>
    </div>


    <!-- ************************************************** -->

    <div class="col2">
    </div>
  </div>
</div>


<!-- ************************************************** -->

<div id="TOC">
  <ul>
    <li class="funding">
      <form action="https://www.paypal.com/cgi-bin/webscr"
            method="post"
            target="_top">
        <input type="hidden"
               name="cmd"
               value="_s-xclick">
        <input type="hidden"
               name="hosted_button_id"
               value="SK827YKEALMT4">
        <input type="submit"
               value="Donate"
               name="submit"
               alt="PayPal - The safer, easier way to pay online!">
      </form>
    </li>
    <li class="primary">
      <a href="http://freetype.org/index.html">Home</a>
    </li>
    <li class="primary">
      <a href="http://freetype.org/index.html#news">News</a>
    </li>
    <li class="primary">
      <a href="../index.html">Overview</a>
    </li>
    <li class="primary">
      <a href="../documentation.html">Documentation</a>
    </li>
    <li class="primary">
      <a href="http://freetype.org/developer.html">Development</a>
    </li>
    <li class="primary">
      <a href="http://freetype.org/contact.html"
         class="emphasis">Contact</a>
    </li>

    <li>
      &nbsp; <!-- separate primary from secondary entries -->
    </li>

    <li class="secondary">
      <a href="index.html">FreeType Design</a>
    </li>
    <li class="tertiary">
      <a href="design-1.html">Introduction</a>
    </li>
    <li class="tertiary">
      <a href="design-2.html">Components and APIs</a>
    </li>
    <li class="tertiary">
      <a href="design-3.html">Public Objects and Classes</a>
    </li>
    <li class="tertiary">
      <a href="design-4.html">Internal Objects and Classes</a>
    </li>
    <li class="tertiary">
      <a href="design-5.html" class="current">Module Classes</a>
    </li>
    <li class="tertiary">
      <a href="design-6.html">Interfaces and Services</a>
    </li>
  </ul>
</div>

</div> <!-- id="wrapper" -->

<div id="TOC-bottom">
</div>

</body>
</html>
